From 03c35d6062ba46e916fc981c581e752c4dceb19a Mon Sep 17 00:00:00 2001 From: Ivan Ukhov Date: Wed, 18 Nov 2015 13:19:13 +0100 Subject: [PATCH] Use proper quotation marks --- src/doc/build-script.md | 84 +++++++++++++++---------------- src/doc/config.md | 4 +- src/doc/crates-io.md | 58 ++++++++++----------- src/doc/environment-variables.md | 2 +- src/doc/faq.md | 10 ++-- src/doc/guide.md | 86 ++++++++++++++++---------------- src/doc/index.md | 16 +++--- src/doc/manifest.md | 32 ++++++------ 8 files changed, 146 insertions(+), 146 deletions(-) diff --git a/src/doc/build-script.md b/src/doc/build-script.md index 8874bf912..feb98fc45 100644 --- a/src/doc/build-script.md +++ b/src/doc/build-script.md @@ -37,8 +37,8 @@ the build command works. When the build script is run, there are a number of inputs to the build script, all passed in the form of [environment variables][env]. -In addition to environment variables, the build script's current directory is -the source directory of the build script's package. +In addition to environment variables, the build script’s current directory is +the source directory of the build script’s package. [env]: environment-variables.html @@ -87,7 +87,7 @@ foo = { git = "https://github.com/your-packages/foo" } ``` The build script **does not** have access to the dependencies listed in the -`dependencies` or `dev-dependencies` section (they're not built yet!). All build +`dependencies` or `dev-dependencies` section (they’re not built yet!). All build dependencies will also not be available to the package itself unless explicitly stated as so. @@ -113,7 +113,7 @@ of native dependencies that a package has, as well as providing a principled system of passing metadata between package build scripts. Primarily, Cargo requires that there is at most one package per `links` value. -In other words, it's forbidden to have two packages link to the same native +In other words, it’s forbidden to have two packages link to the same native library. Note, however, that there are [conventions in place][star-sys] to alleviate this. @@ -161,10 +161,10 @@ instead be used. # Case study: Code generation Some Cargo packages need to have code generated just before they are compiled -for various reasons. Here we'll walk through a simple example which generates a +for various reasons. Here we’ll walk through a simple example which generates a library call as part of the build script. -First, let's take a look at the directory structure of this package: +First, let’s take a look at the directory structure of this package: ```notrust . @@ -177,7 +177,7 @@ First, let's take a look at the directory structure of this package: ``` Here we can see that we have a `build.rs` build script and our binary in -`main.rs`. Next, let's take a look at the manifest: +`main.rs`. Next, let’s take a look at the manifest: ```toml # Cargo.toml @@ -189,8 +189,8 @@ authors = ["you@example.com"] build = "build.rs" ``` -Here we can see we've got a build script specified which we'll use to generate -some code. Let's see what's inside the build script: +Here we can see we’ve got a build script specified which we’ll use to generate +some code. Let’s see what’s inside the build script: ```rust,no_run // build.rs @@ -213,18 +213,18 @@ fn main() { } ``` -There's a couple of points of note here: +There’s a couple of points of note here: * The script uses the `OUT_DIR` environment variable to discover where the - output files should be located. It can use the process's current working + output files should be located. It can use the process’ current working directory to find where the input files should be located, but in this case we - don't have any input files. + don’t have any input files. * This script is relatively simple as it just writes out a small generated file. One could imagine that other more fanciful operations could take place such as generating a Rust module from a C header file or another language definition, for example. -Next, let's peek at the library itself: +Next, let’s peek at the library itself: ```rust,ignore // src/main.rs @@ -238,21 +238,21 @@ fn main() { This is where the real magic happens. The library is using the rustc-defined `include!` macro in combination with the `concat!` and `env!` macros to include -the generated file (`mod.rs`) into the crate's compilation. +the generated file (`mod.rs`) into the crate’s compilation. Using the structure shown here, crates can include any number of generated files -from the build script itself. We've also seen a brief example of how a build +from the build script itself. We’ve also seen a brief example of how a build script can use a crate as a dependency purely for the build process and not for the crate itself at runtime. # Case study: Building some native code -Sometimes it's necessary to build some native C or C++ code as part of a +Sometimes it’s necessary to build some native C or C++ code as part of a package. This is another excellent use case of leveraging the build script to -build a native library before the Rust crate itself. As an example, we'll create -a Rust library which calls into C to print "Hello, World!". +build a native library before the Rust crate itself. As an example, we’ll create +a Rust library which calls into C to print “Hello, World!”. -Like above, let's first take a look at the project layout: +Like above, let’s first take a look at the project layout: ```notrust . @@ -277,7 +277,7 @@ authors = ["you@example.com"] build = "build.rs" ``` -For now we're not going to use any build dependencies, so let's take a look at +For now we’re not going to use any build dependencies, so let’s take a look at the build script now: ```rust,no_run @@ -312,11 +312,11 @@ statically via the `-l static=hello` flag. Note that there are a number of drawbacks to this hardcoded approach: -* The `gcc` command itself is not portable across platforms. For example it's +* The `gcc` command itself is not portable across platforms. For example it’s unlikely that Windows platforms have `gcc`, and not even all Unix platforms may have `gcc`. The `ar` command is also in a similar situation. -* These commands do not take cross-compilation into account. If we're cross - compiling for a platform such as Android it's unlikely that `gcc` will produce +* These commands do not take cross-compilation into account. If we’re cross + compiling for a platform such as Android it’s unlikely that `gcc` will produce an ARM executable. Not to fear, though, this is where a `build-dependencies` entry would help! The @@ -359,7 +359,7 @@ Here we can start to see some of the major benefits of farming as much functionality as possible out to common build dependencies rather than duplicating logic across all build scripts! -Back to the case study though, let's take a quick look at the contents of the +Back to the case study though, let’s take a quick look at the contents of the `src` directory: ```c @@ -375,7 +375,7 @@ void hello() { ```rust,ignore // src/main.rs -// Note the lack of the `#[link]` attribute. We're delegating the responsibility +// Note the lack of the `#[link]` attribute. We’re delegating the responsibility // of selecting what to link to over to the build script rather than hardcoding // it in the source file. extern { fn hello(); } @@ -401,7 +401,7 @@ performing this in a platform-agnostic fashion, and the purpose of a build script is again to farm out as much of this as possible to make this as easy as possible for consumers. -As an example to follow, let's take a look at one of [Cargo's own +As an example to follow, let’s take a look at one of [Cargo’s own dependencies][git2-rs], [libgit2][libgit2]. This library has a number of constraints: @@ -415,7 +415,7 @@ constraints: * It is often not installed on all systems by default. * It can be built from source using `cmake`. -To visualize what's going on here, let's take a look at the manifest for the +To visualize what’s going on here, let’s take a look at the manifest for the relevant Cargo package. ```toml @@ -435,7 +435,7 @@ openssl-sys = { git = "https://github.com/alexcrichton/openssl-sys" } # ... ``` -As the above manifests show, we've got a `build` script specified, but it's +As the above manifests show, we’ve got a `build` script specified, but it’s worth noting that this example has a `links` entry which indicates that the crate (`libgit2-sys`) links to the `git2` native library. @@ -443,7 +443,7 @@ Here we also see the unconditional dependency on `libssh2` via the `libssh2-sys` crate, as well as a platform-specific dependency on `openssl-sys` for unix (other variants elided for now). It may seem a little counterintuitive to express *C dependencies* in the *Cargo manifest*, but this is actually using -one of Cargo's conventions in this space. +one of Cargo’s conventions in this space. ## `*-sys` Packages @@ -469,40 +469,40 @@ convention of native-library-related packages: ## Building libgit2 -Now that we've got libgit2's dependencies sorted out, we need to actually write -the build script. We're not going to look at specific snippets of code here and +Now that we’ve got libgit2’s dependencies sorted out, we need to actually write +the build script. We’re not going to look at specific snippets of code here and instead only take a look at the high-level details of the build script of `libgit2-sys`. This is not recommending all packages follow this strategy, but rather just outlining one specific strategy. The first step of the build script should do is to query whether libgit2 is -already installed on the host system. To do this we'll leverage the preexisting -tool `pkg-config` (when its available). We'll also use a `build-dependencies` -section to refactor out all the `pkg-config` related code (or someone's already +already installed on the host system. To do this we’ll leverage the preexisting +tool `pkg-config` (when its available). We’ll also use a `build-dependencies` +section to refactor out all the `pkg-config` related code (or someone’s already done that!). -If `pkg-config` failed to find libgit2, or if `pkg-config` just wasn't +If `pkg-config` failed to find libgit2, or if `pkg-config` just wasn’t installed, the next step is to build libgit2 from bundled source code (distributed as part of `libgit2-sys` itself). There are a few nuances when doing so that we need to take into account, however: -* The build system of libgit2, `cmake`, needs to be able to find libgit2's - optional dependency of libssh2. We're sure we've already built it (it's a +* The build system of libgit2, `cmake`, needs to be able to find libgit2’s + optional dependency of libssh2. We’re sure we’ve already built it (it’s a Cargo dependency), we just need to communicate this information. To do this we leverage the metadata format to communicate information between build scripts. In this example the libssh2 package printed out `cargo:root=...` to tell us where libssh2 is installed at, and we can then pass this along to cmake with the `CMAKE_PREFIX_PATH` environment variable. -* We'll need to handle some `CFLAGS` values when compiling C code (and tell +* We’ll need to handle some `CFLAGS` values when compiling C code (and tell `cmake` about this). Some flags we may want to pass are `-m64` for 64-bit code, `-m32` for 32-bit code, or `-fPIC` for 64-bit code as well. -* Finally, we'll invoke `cmake` to place all output into the `OUT_DIR` - environment variable, and then we'll print the necessary metadata to instruct +* Finally, we’ll invoke `cmake` to place all output into the `OUT_DIR` + environment variable, and then we’ll print the necessary metadata to instruct rustc how to link to libgit2. Most of the functionality of this build script is easily refactorable into -common dependencies, so our build script isn't quite as intimidating as this -descriptions! In reality it's expected that build scripts are quite succinct by +common dependencies, so our build script isn’t quite as intimidating as this +descriptions! In reality it’s expected that build scripts are quite succinct by farming logic such as above to build dependencies. diff --git a/src/doc/config.md b/src/doc/config.md index ff7b11d6b..da0e206e7 100644 --- a/src/doc/config.md +++ b/src/doc/config.md @@ -1,6 +1,6 @@ % Configuration - Cargo Documentation -This document will explain how cargo's configuration system works, as well as +This document will explain how cargo’s configuration system works, as well as available keys or configuration. For configuration of a project through its manifest, see the [manifest format](manifest.html). @@ -74,7 +74,7 @@ linker = ".." # Configuration keys related to the registry [registry] index = "..." # URL of the registry index (defaults to the central repository) -token = "..." # Access token (found on the central repo's website) +token = "..." # Access token (found on the central repo’s website) [http] proxy = "..." # HTTP proxy to use for HTTP requests (defaults to none) diff --git a/src/doc/crates-io.md b/src/doc/crates-io.md index 6ed695722..a21cb3fff 100644 --- a/src/doc/crates-io.md +++ b/src/doc/crates-io.md @@ -22,7 +22,7 @@ syntax for doing so is: glob = "0.0.3" ``` -With this format, adding new dependencies should just add a new line, you don't +With this format, adding new dependencies should just add a new line, you don’t need to add `[dependencies]` for each dependency listed, for example: ```toml @@ -40,7 +40,7 @@ requirement. `^1.2.3` is an example of a caret requirement. -When considering ‘compatible’ versions, `0.1` and `0.2` are not considered +When considering “compatible” versions, `0.1` and `0.2` are not considered compatible, but `1.0` and `1.1` are for example. If no operator is specified, this is the default requirement (e.g. `1.3` is the same as `^1.3`). @@ -101,8 +101,8 @@ compatible. # Publishing crates -Ok, now that we've got a crate which is using dependencies from crates.io, -let's publish it! Publishing a crate is when a specific version is uploaded to +Ok, now that we’ve got a crate which is using dependencies from crates.io, +let’s publish it! Publishing a crate is when a specific version is uploaded to crates.io. Take care when publishing a crate, because a publish is **permanent**. The @@ -111,7 +111,7 @@ limit to the number of versions which can be published, however. ## Acquiring an API token -First thing's first, you'll need an account on [crates.io][crates-io] to acquire +First thing’s first, you’ll need an account on [crates.io][crates-io] to acquire an API token. To do so, [visit the home page][crates-io] and log in via a GitHub account (required for now). After this, visit your [Account Settings](https://crates.io/me) page and run the `cargo login` command @@ -129,7 +129,7 @@ immediately. ## Packaging a crate The next step is to package up your crate into a format that can be uploaded to -crates.io. For this we'll use the `cargo package` subcommand. This will take +crates.io. For this we’ll use the `cargo package` subcommand. This will take our entire crate and package it all up into a `*.crate` file in the `target/package` directory. @@ -138,12 +138,12 @@ $ cargo package ``` As an added bonus, the `*.crate` will be verified independently of the current -source tree. After the `*.crate` is created, it's unpacked into +source tree. After the `*.crate` is created, it’s unpacked into `target/package` and then built from scratch to ensure that all necessary files are there for the build to succeed. This behavior can be disabled with the `--no-verify` flag. -Now's a good time to take a look at the `*.crate` file to make sure you didn't +Now’s a good time to take a look at the `*.crate` file to make sure you didn’t accidentally package up that 2GB video asset. Cargo will automatically ignore files ignored by your version control system when packaging, but if you want to specify an extra set of files to ignore you can use the `exclude` key in the @@ -159,7 +159,7 @@ exclude = [ ``` The syntax of each element in this array is what -[rust-lang/glob](https://github.com/rust-lang/glob) accepts. If you'd rather +[rust-lang/glob](https://github.com/rust-lang/glob) accepts. If you’d rather roll with a whitelist instead of a blacklist, Cargo also supports an `include` key: @@ -174,16 +174,16 @@ include = [ ## Uploading the crate -Now that we've got a `*.crate` file ready to go, it can be uploaded to -crates.io with the `cargo publish` command. And that's it, you've now published +Now that we’ve got a `*.crate` file ready to go, it can be uploaded to +crates.io with the `cargo publish` command. And that’s it, you’ve now published your first crate! ```notrust $ cargo publish ``` -If you'd like to skip the `cargo package` step, the `cargo publish` subcommand -will automatically package up the local crate if a copy isn't found already. +If you’d like to skip the `cargo package` step, the `cargo publish` subcommand +will automatically package up the local crate if a copy isn’t found already. Be sure to check out the [metadata you can specify](manifest.html#package-metadata) to ensure your crate can be discovered @@ -209,7 +209,7 @@ to manage a crate. Occasions may arise where you publish a version of a crate that actually ends up being broken for one reason or another (syntax error, forgot to include a file, -etc). For situations such as this, Cargo supports a "yank" of a version of a +etc). For situations such as this, Cargo supports a “yank” of a version of a crate. ```notrust @@ -244,14 +244,14 @@ $ cargo owner --remove github:rust-lang:owners The owner IDs given to these commands must be GitHub user names or Github teams. -If a user name is given to `--add`, that user becomes a "named" owner, with +If a user name is given to `--add`, that user becomes a “named” owner, with full rights to the crate. In addition to being able to publish or yank versions of the crate, they have the ability to add or remove owners, *including* the -owner that made *them* an owner. Needless to say, you shouldn't make people you -don't fully trust into a named owner. In order to become a named owner, a user +owner that made *them* an owner. Needless to say, you shouldn’t make people you +don’t fully trust into a named owner. In order to become a named owner, a user must have logged into crates.io previously. -If a team name is given to `--add`, that team becomes a "team" owner, with +If a team name is given to `--add`, that team becomes a “team” owner, with restricted right to the crate. While they have permission to publish or yank versions of the crate, they *do not* have the ability to add or remove owners. In addition to being more convenient for managing groups of owners, teams are @@ -266,18 +266,18 @@ such restriction applies to removing a team as an owner. Team membership is not something Github provides simple public access to, and it is likely for you to encounter the following message when working with them: -> It looks like you don't have permission to query a necessary property from +> It looks like you don’t have permission to query a necessary property from Github to complete this request. You may need to re-authenticate on crates.io to grant permission to read github org memberships. Just go to https://crates.io/login -This is basically a catch-all for "you tried to query a team, and one of the -five levels of membership access control denied this". That is not an -exaggeration. Github's support for team access control is Enterprise Grade. +This is basically a catch-all for “you tried to query a team, and one of the +five levels of membership access control denied this”. That is not an +exaggeration. Github’s support for team access control is Enterprise Grade. The most likely cause of this is simply that you last logged in before this feature was added. We originally requested *no* permissions from Github when -authenticating users, because we didn't actually ever use the user's token for +authenticating users, because we didn’t actually ever use the user’s token for anything other than logging them in. However to query team membership on your behalf, we now require [the `read:org` scope](https://developer.github.com/v3/oauth/#scopes). @@ -286,11 +286,11 @@ You are free to deny us this scope, and everything that worked before teams were introduced will keep working. However you will never be able to add a team as an owner, or publish a crate as a team owner. If you ever attempt to do this, you will get the error above. You may also see this error if you ever try to -publish a crate that you don't own at all, but otherwise happens to have a team. +publish a crate that you don’t own at all, but otherwise happens to have a team. -If you ever change your mind, or just aren't sure if crates.io has sufficient +If you ever change your mind, or just aren’t sure if crates.io has sufficient permission, you can always go to https://crates.io/login, which will prompt you -for permission if crates.io doesn't have all the scopes it would like to. +for permission if crates.io doesn’t have all the scopes it would like to. An additional barrier to querying github is that the organization may be actively denying third party access. To check this, you can go to: @@ -302,12 +302,12 @@ something like: ![Organization Access Control](images/org-level-acl.png) -Where you may choose to explicitly remove crates.io from your organization's -blacklist, or simply press the "Remove Restrictions" button to allow all third +Where you may choose to explicitly remove crates.io from your organization’s +blacklist, or simply press the “Remove Restrictions” button to allow all third party applications to access this data. Alternatively, when crates.io requested the `read:org` scope, you could have explicitly whitelisted crates.io querying the org in question by pressing -the "Grant Access" button next to its name: +the “Grant Access” button next to its name: ![Authentication Access Control](images/auth-level-acl.png) diff --git a/src/doc/environment-variables.md b/src/doc/environment-variables.md index 3ffc2c3fb..0b40f0bc0 100644 --- a/src/doc/environment-variables.md +++ b/src/doc/environment-variables.md @@ -42,7 +42,7 @@ Here are a list of the variables Cargo sets, organized by when it sets them: unique for the package in question. * `TARGET` - the target triple that is being compiled for. Native code should be compiled for this triple. Some more information about target - triples can be found in [clang's own documentation][clang]. + triples can be found in [clang’s own documentation][clang]. * `HOST` - the host triple of the rust compiler. * `NUM_JOBS` - the parallelism specified as the top-level parallelism. This can be useful to pass a `-j` parameter to a system like `make`. diff --git a/src/doc/faq.md b/src/doc/faq.md index 61e0e8d61..737090eb2 100644 --- a/src/doc/faq.md +++ b/src/doc/faq.md @@ -11,14 +11,14 @@ even when people use the registry as the primary source of packages. # Why build crates.io rather than use Github as a registry? -We think that it's very important to support multiple ways to download +We think that it’s very important to support multiple ways to download packages, including downloading from Github and copying packages into your project itself. That said, we think that crates.io offers a number of important benefits, and will likely become the primary way that people download packages in Cargo. -For precedent, both Node.js's [npm][1] and Ruby's [bundler][2] support both a +For precedent, both Node.js’s [npm][1] and Ruby’s [bundler][2] support both a central registry model as well as a Git-based model, and most packages are downloaded through the registry in those ecosystems, with an important minority of packages making use of git-based packages. @@ -76,7 +76,7 @@ configuration in `Cargo.toml` in the future. [target-deps]: manifest.html#the-dependencies-section -In the longer-term, we're looking at ways to conveniently cross-compile +In the longer-term, we’re looking at ways to conveniently cross-compile projects using Cargo. # Does Cargo support environments, like `production` or `test`? @@ -114,11 +114,11 @@ all binaries check in their `Cargo.lock`. For libraries the situation is somewhat different. A library is not only used by the library developers, but also any downstream consumers of the library. Users -dependent on the library will not inspect the library's `Cargo.lock` (even if it +dependent on the library will not inspect the library’s `Cargo.lock` (even if it exists). This is precisely because a library should **not** be deterministically recompiled for all users of the library. -If a library ends up being used transitively by several dependencies, it's +If a library ends up being used transitively by several dependencies, it’s likely that just a single copy of the library is desired (based on semver compatibility). If all libraries were to check in their `Cargo.lock`, then multiple copies of the library would be used, and perhaps even a version diff --git a/src/doc/guide.md b/src/doc/guide.md index 5b40a95fd..80f750847 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -6,18 +6,18 @@ about how to use Cargo to develop Rust projects. # Why Cargo exists Cargo is a tool that allows Rust projects to declare their various -dependencies, and ensure that you'll always get a repeatable build. +dependencies, and ensure that you’ll always get a repeatable build. To accomplish this goal, Cargo does four things: * Introduces two metadata files with various bits of project information. -* Fetches and builds your project's dependencies. +* Fetches and builds your project’s dependencies. * Invokes `rustc` or another build tool with the correct parameters to build your project. * Introduces conventions, making working with Rust projects easier. # Converting to Cargo -You can convert an existing Rust project to use Cargo. You'll have to create a +You can convert an existing Rust project to use Cargo. You’ll have to create a `Cargo.toml` file with all of your dependencies, and move your source files and test files into the places where Cargo expects them to be. See the [manifest description](manifest.html) and the [Project Layout](#project-layout) section @@ -31,11 +31,11 @@ To start a new project with Cargo, use `cargo new`: $ cargo new hello_world --bin ``` -We're passing `--bin` because we're making a binary program: if we -were making a library, we'd leave it off. If you'd like to not initialize a new +We’re passing `--bin` because we’re making a binary program: if we +were making a library, we’d leave it off. If you’d like to not initialize a new git repository as well (the default), you can also pass `--vcs none`. -Let's check out what Cargo has generated for us: +Let’s check out what Cargo has generated for us: ```shell $ cd hello_world @@ -50,7 +50,7 @@ $ tree . If we had just used `cargo new hello_world` without the `--bin` flag, then the we would have a `lib.rs` instead of a `main.rs`. For now, however, this is all -we need to get started. First, let's check out `Cargo.toml`: +we need to get started. First, let’s check out `Cargo.toml`: ```toml [package] @@ -62,7 +62,7 @@ authors = ["Your Name "] This is called a **manifest**, and it contains all of the metadata that Cargo needs to compile your project. -Here's what's in `src/main.rs`: +Here’s what’s in `src/main.rs`: ``` fn main() { @@ -70,7 +70,7 @@ fn main() { } ``` -Cargo generated a 'hello world' for us. Let's compile it: +Cargo generated a “hello world” for us. Let’s compile it: 
$ cargo build
    Running `target/debug/hello_world`
 Hello, world!
To pass some arguments to your program, use `cargo run first_arg second_arg`. -If flags are being passed, use a '--' separator to tell Cargo which flags go where, like `cargo run -- --foo -b bar`. +If flags are being passed, use a “--” separator to tell Cargo which flags go where, like `cargo run -- --foo -b bar`. -You'll now notice a new file, `Cargo.lock`. It contains information about our -dependencies. Since we don't have any yet, it's not very interesting. +You’ll now notice a new file, `Cargo.lock`. It contains information about our +dependencies. Since we don’t have any yet, it’s not very interesting. -Once you're ready for release, you can use `cargo build --release` to compile your files with optimizations turned on: +Once you’re ready for release, you can use `cargo build --release` to compile your files with optimizations turned on: 
$ cargo build --release
    Compiling hello_world v0.1.0 (file:///path/to/project/hello
 
 # Working on an existing Cargo project
 
-If you download an existing project that uses Cargo, it's really easy
+If you download an existing project that uses Cargo, it’s really easy
 to get going.
 
-First, get the project from somewhere. In this example, we'll use `color-rs`:
+First, get the project from somewhere. In this example, we’ll use `color-rs`:
 
 ```sh
 $ git clone https://github.com/bjz/color-rs.git
@@ -130,7 +130,7 @@ To depend on a library, add it to your `Cargo.toml`.
 
 ## Adding a dependency
 
-It's quite simple to add a dependency. Simply add it to your `Cargo.toml` file:
+It’s quite simple to add a dependency. Simply add it to your `Cargo.toml` file:
 
 ```toml
 [dependencies]
@@ -217,14 +217,14 @@ description](manifest.html#the-project-layout).
 # Cargo.toml vs Cargo.lock
 
 `Cargo.toml` and `Cargo.lock` serve two different purposes. Before we talk
-about them, here's a summary:
+about them, here’s a summary:
 
 * `Cargo.toml` is about describing your dependencies in a broad sense, and is written by you.
 * `Cargo.lock` contains exact information about your dependencies, and is maintained by Cargo.
-* If you're building a library, put `Cargo.lock` in your `.gitignore`.
-* If you're building an executable, check `Cargo.lock` into `git`.
+* If you’re building a library, put `Cargo.lock` in your `.gitignore`.
+* If you’re building an executable, check `Cargo.lock` into `git`.
 
-Let's dig in a little bit more.
+Let’s dig in a little bit more.
 
 `Cargo.toml` is a **manifest** file. In the manifest, we can specify a bunch of
 different metadata about our project. For example, we can say that we depend
@@ -240,12 +240,12 @@ authors = ["Your Name "]
 color = { git = "https://github.com/bjz/color-rs.git" }
 ```
 
-This project has a single dependency, on the `color` library. We've stated in
-this case that we're relying on a particular Git repository that lives on
-GitHub. Since we haven't specified any other information, Cargo assumes that
+This project has a single dependency, on the `color` library. We’ve stated in
+this case that we’re relying on a particular Git repository that lives on
+GitHub. Since we haven’t specified any other information, Cargo assumes that
 we intend to use the latest commit on the `master` branch to build our project.
 
-Sound good? Well, there's one problem: If you build this project today, and
+Sound good? Well, there’s one problem: If you build this project today, and
 then you send a copy to me, and I build this project tomorrow, something bad
 could happen. `bjz` could update `color-rs` in the meantime, and my build would
 include this commit, while yours would not. Therefore, we would get different
@@ -258,11 +258,11 @@ We could fix this problem by putting a `rev` line in our `Cargo.toml`:
 color = { git = "https://github.com/bjz/color-rs.git", rev = "bf739419" }
 ```
 
-Now, our builds will be the same. But, there's a big drawback: now we have to
+Now, our builds will be the same. But, there’s a big drawback: now we have to
 manually think about SHA-1s every time we want to update our library. This is
 both tedious and error prone.
 
-Enter the `Cargo.lock`. Because of its existence, we don't need to manually
+Enter the `Cargo.lock`. Because of its existence, we don’t need to manually
 keep track of the exact revisions: Cargo will do it for us. When we have a
 manifest like this:
 
@@ -294,17 +294,17 @@ source = "git+https://github.com/bjz/color-rs.git#bf739419e2d31050615c1ba1a395b4
 
 ```
 
-You can see that there's a lot more information here, including the exact
+You can see that there’s a lot more information here, including the exact
 revision we used to build. Now, when you give your project to someone else,
-they'll use the exact same SHA, even though we didn't specify it in our
+they’ll use the exact same SHA, even though we didn’t specify it in our
 `Cargo.toml`.
 
-When we're ready to opt in to a new version of the library, Cargo can
+When we’re ready to opt in to a new version of the library, Cargo can
 re-calculate the dependencies, and update things for us:
 
 ```shell
 $ cargo update           # updates all dependencies
-$ cargo update -p color  # updates just 'color'
+$ cargo update -p color  # updates just “color”
 ```
 
 This will write out a new `Cargo.lock` with the new version information. Note
@@ -314,10 +314,10 @@ specification.
 
 # Overriding Dependencies
 
-Sometimes, you may want to override one of Cargo's dependencies. For example,
-let's say you're working on a project, `conduit-static`, which depends on
+Sometimes, you may want to override one of Cargo’s dependencies. For example,
+let’s say you’re working on a project, `conduit-static`, which depends on
 the package `conduit`. You find a bug in `conduit`, and you want to write a
-patch. Here's what `conduit-static`'s `Cargo.toml` looks like:
+patch. Here’s what `conduit-static`’s `Cargo.toml` looks like:
 
 ```toml
 [package]
@@ -329,14 +329,14 @@ authors = ["Yehuda Katz "]
 conduit = "0.7"
 ```
 
-You check out a local copy of `conduit`, let's say in your `~/src` directory:
+You check out a local copy of `conduit`, let’s say in your `~/src` directory:
 
 ```shell
 $ cd ~/src
 $ git clone https://github.com/conduit-rust/conduit.git
 ```
 
-You'd like to have `conduit-static` use your local version of `conduit`,
+You’d like to have `conduit-static` use your local version of `conduit`,
 rather than the one on GitHub, while you fix the bug.
 
 Cargo solves this problem by allowing you to have a local configuration
@@ -359,7 +359,7 @@ includes commonly used packages that you work on locally, and share them
 with all projects.
 
 To specify overrides, create a `.cargo/config` file in some ancestor of
-your project's directory (common places to put it is in the root of
+your project’s directory (common places to put it is in the root of
 your code directory or in your home directory).
 
 Inside that file, put this:
@@ -369,7 +369,7 @@ paths = ["/path/to/project/conduit"]
 ```
 
 This array should be filled with directories that contain a `Cargo.toml`. In
-this instance, we're just adding `conduit`, so it will be the only one that's
+this instance, we’re just adding `conduit`, so it will be the only one that’s
 overridden. This path must be an absolute path.
 
 Note: using a local configuration to override paths will only work for crates
@@ -384,7 +384,7 @@ documentation](config.html).
 Cargo can run your tests with the `cargo test` command. Cargo runs tests in two
 places: in each of your `src` files, and any tests in `tests/`. Tests
 in your `src` files should be unit tests, and tests in `tests/` should be
-integration-style tests. As such, you'll need to import your crates into
+integration-style tests. As such, you’ll need to import your crates into
 the files in `tests`.
 
 To run your tests, just run `cargo test`:
@@ -402,7 +402,7 @@ running 0 tests
 test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured
-Of course, if your project has tests, you'll see more output, with the +Of course, if your project has tests, you’ll see more output, with the correct number of tests. You can also run a specific test by passing a filter: @@ -421,10 +421,10 @@ documentation for more details. # Path Dependencies -Over time our `hello_world` project has grown significantly in size! It's gotten +Over time our `hello_world` project has grown significantly in size! It’s gotten to the point that we probably want to split out a separate crate for others to use. To do this Cargo supports **path dependencies** which are typically -sub-crates that live within one repository. Let's start off by making a new +sub-crates that live within one repository. Let’s start off by making a new crate inside of our `hello_world` project: ```shell @@ -442,9 +442,9 @@ hello_utils = { path = "hello_utils" } ``` This tells Cargo that we depend on a crate called `hello_utils` which is found -in the `hello_utils` folder (relative to the `Cargo.toml` it's written in). +in the `hello_utils` folder (relative to the `Cargo.toml` it’s written in). -And that's it! The next `cargo build` will automatically build `hello_utils` and +And that’s it! The next `cargo build` will automatically build `hello_utils` and all of its own dependencies, and others can also start using the crate as well. ## Travis-CI diff --git a/src/doc/index.md b/src/doc/index.md index 699c808f4..492c9e86c 100644 --- a/src/doc/index.md +++ b/src/doc/index.md @@ -1,4 +1,4 @@ -% Cargo, Rust's Package Manager +% Cargo, Rust’s Package Manager # Installing @@ -17,7 +17,7 @@ and [Cargo](https://static.rust-lang.org/cargo-dist/cargo-nightly-i686-pc-window Alternatively, you can build Cargo from source. -# Let's Get Started +# Let’s Get Started To start a new project with Cargo, use `cargo new`: @@ -25,10 +25,10 @@ To start a new project with Cargo, use `cargo new`: $ cargo new hello_world --bin ``` -We're passing `--bin` because we're making a binary program: if we -were making a library, we'd leave it off. +We’re passing `--bin` because we’re making a binary program: if we +were making a library, we’d leave it off. -Let's check out what Cargo has generated for us: +Let’s check out what Cargo has generated for us: ```shell $ cd hello_world @@ -41,7 +41,7 @@ $ tree . 1 directory, 2 files ``` -This is all we need to get started. First, let's check out `Cargo.toml`: +This is all we need to get started. First, let’s check out `Cargo.toml`: ```toml [package] @@ -53,7 +53,7 @@ authors = ["Your Name "] This is called a **manifest**, and it contains all of the metadata that Cargo needs to compile your project. -Here's what's in `src/main.rs`: +Here’s what’s in `src/main.rs`: ``` fn main() { @@ -61,7 +61,7 @@ fn main() { } ``` -Cargo generated a 'hello world' for us. Let's compile it: +Cargo generated a “hello world” for us. Let’s compile it: 
$ cargo build